Skip to content

params.Frame: Add parameters for 3-D plots#4594

Open
seisman wants to merge 9 commits intomainfrom
codex/frame-3d-modifiers
Open

params.Frame: Add parameters for 3-D plots#4594
seisman wants to merge 9 commits intomainfrom
codex/frame-3d-modifiers

Conversation

@seisman
Copy link
Copy Markdown
Member

@seisman seisman commented Apr 19, 2026 •
edited
Loading

This PR adds parameters for -B modifiers related to 3-D plots:

  • +b: box
  • +w: wall_pen
  • +x: yzfill
  • +y: xzfill
  • +z: xyfill

GMT uses pen for +b (xref: https://github.com/GenericMappingTools/gmt/blob/ac580b28da697232ae21cfa2ec102610572af2d8/src/gmt_common_longoptions.h#L72), but I feel pen is too general, and it's also a little misleading because it only sets pen for x-z and y-z planes, not the frame pen for the x-y plane.

Example

import pygmt
from pygmt.params import Axis, Frame

fig = pygmt.Figure()
fig.basemap(
    region=(0, 1, 0, 2, 0, 3),
    projection="X10c/10c",
    zsize="5c",
    perspective=(120, 30),
    frame=Frame(
        axes="WSENZ",
        axis=True,
        zaxis=True,
        box=True,
        wall_pen="1p,red",
        xzfill="lightgreen",
        xyfill="lightblue",
        yzfill="lightyellow",
    )
)
fig.show()
map

Related to #4588

@seisman seisman changed the title Add 3-D Frame modifiers params.Frame: Add parameters for 3-D plots Apr 19, 2026
@seisman seisman added enhancement Improving an existing feature needs review This PR has higher priority and needs review. labels Apr 19, 2026
@seisman seisman added this to the 0.19.0 milestone Apr 19, 2026
@seisman seisman mentioned this pull request Apr 19, 2026
Open
40 tasks
@seisman seisman requested a review from yvonnefroehlich April 19, 2026 05:56
@seisman seisman requested a review from a team April 23, 2026 02:10
@seisman seisman added final review call This PR requires final review and approval from a second reviewer and removed needs review This PR has higher priority and needs review. labels Apr 29, 2026
yvonnefroehlich
yvonnefroehlich reviewed Apr 29, 2026
View reviewed changes
Comment thread pygmt/tests/test_params_frame.py
Comment on lines +55 to +59
fill="gray",
wall_pen="0.5p,black",
yzfill="red",
xzfill="green",
xyfill="blue",
Copy link
Copy Markdown
Member

@yvonnefroehlich yvonnefroehlich Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe if all three of yzfill, xzfill and xyfill are used, fill will not have an effect.

Copy link
Copy Markdown
Member Author

@seisman seisman Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, fill sets the fill of the three back-faces but can be overridden by yzfill/xzfill/xyfill. We need to improve the docstring to clarify it.

Actually, as a non-native English speaker, I don't know the standard terminology to describe the elements of a cube. Currently, we describe them as "frontground lines", "outlines of x-z and y-z planes", "yz-plane"/"xz-plane"/"xy-plane", but it seems in standard terminology, they should be called faces (front face? back face?), and edges.

@yvonnefroehlich
Copy link
Copy Markdown
Member

yvonnefroehlich commented Apr 29, 2026

GMT uses pen for +b (xref: https://github.com/GenericMappingTools/gmt/blob/ac580b28da697232ae21cfa2ec102610572af2d8/src/gmt_common_longoptions.h#L72), but I feel pen is too general, and it's also a little misleading because it only sets pen for x-z and y-z planes, not the frame pen for the x-y plane.

I like box for +b.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@yvonnefroehlich yvonnefroehlich yvonnefroehlich left review comments

@michaelgrund michaelgrund michaelgrund approved these changes

Assignees

No one assigned

Labels

enhancement Improving an existing feature final review call This PR requires final review and approval from a second reviewer

Projects

None yet

Milestone

0.19.0

Development

Successfully merging this pull request may close these issues.

3 participants

@seisman @yvonnefroehlich @michaelgrund